/**
 * @file m_list.h
 * @brief 先入先出列表（内部没锁！！！）
 *
 * @code 例
 *  init:
 *      MListTag list;
 *
 *      MListCreate(&list);
 *      MListSetCapacity(10);
 *
 *  fini:
 *      MListDestroy(&list);
 *
 *  push:
 *      void *new_item;
 *      MListPush(&list, new_item);
 *
 *  peek:
 *      void *item = MListPeek(&list);
 *  pop:
 *      void *item = MListPop(&list);
 *  loop:
 *      void *item;
 *      MListIteratorReset(&list);
 *      while (item = MListIteratorNext(&list))
 *          or
 *      for (item = MListIteratorNext(&list); item != NULL; item = MListIteratorNext(&list))
 * @endcode
 *
 * @author Liebing.Yang
 * @date 2024/06/01
 *
*/
#ifndef _M_LIST_H_
#define _M_LIST_H_
#include "m_types.h"
#include "m_errno.h"

/**
 * 列表节点结构体
 */
typedef struct MListNodeTag
{
    void *item_;

    struct MListNodeTag *prev_;
    struct MListNodeTag *next_;
} MListNode;

/**
 * 列表 结构体
 */
typedef struct MListTag
{
    MListNode list_head_;

    MListNode *iter_node_;

    Bool is_init_;
    Int32 item_cnt_;
    Int32 capacity_;
}  MList;

/**
 * @brief 创建一个列表
 *
 * @param self: 列表对象
 * @return 执行结果，详见 MErrCode
*/
Int32 MListCreate(MList *self);

/**
 * @brief 摧毁一个列表
 *
 * @param self: 列表对象
 * @return 执行结果，详见 MErrCode
 */
Int32 MListDestroy(MList *self);

/**
 * @brief 设置列表容量，不调用则不限制容量，下次推入时生效
 *
 * @param self: 列表对象
 * @param capacity: 设置的容量
 * @return 执行结果，详见 MErrCode
 */
Int32 MListSetCapacity(MList *self, Int32 capacity);

/**
 * @brief 列表成员个数
 *
 * @param self: 列表对象
 * @retval >=0 返回列表成员数
 * @retval <0 错误码，详见 MErrCode
 */
Int32 MListItemCount(MList *self);

/**
 * @brief 列表成员个数
 *
 * @param self: 列表对象
 * @param item: 待查找的成员
 * @retval >=0 返回成员所在位置
 * @retval <0 错误码，详见 MErrCode
 */
Int32 MListFind(MList *self, void *item);

/**
 * @brief 将新成员推入列表
 *
 * @param self: 列表对象
 * @param new_item: 新成员
 * @return 执行结果，详见 MErrCode
 */
Int32 MListPush(MList *self, void *new_item);

/**
 * @brief 窥探列表的首名成员
 *
 * @param self: 列表对象
 * @return 窥探到的成员，NULL则窥探失败（列表为空，或列表未正确创建）
 */
void* MListPeek(MList *self);

/**
 * @brief 取出列表的首名成员
 *
 * @param self: 列表对象
 * @return 取出的成员，NULL则取出失败（列表为空，或列表未正确创建）
 */
void* MListPop(MList *self);

/**
 * @brief 列表迭代器重置
 *
 * @note 迭代器会在列表Push或Pop时自动重置
 * @param self: 列表对象
 * @return 执行结果，详见 MErrCode
 */
Int32 MListIteratorReset(MList *self);

/**
 * @brief 列表迭代器前移（从后向前），然后返回迭代器成员
 *
 * @note 迭代器会在列表Push或Pop时自动重置
 * @param self: 列表对象
 * @return 执行结果，详见 MErrCode
 */
void* MListIteratorPrev(MList *self);

/**
 * @brief 列表迭代器后移（从前向后），然后返回迭代器成员
 *
 * @note 迭代器会在列表Push或Pop时自动重置
 * @param self: 列表对象
 * @return 执行结果，详见 MErrCode
 */
void* MListIteratorNext(MList *self);

/**
 * @brief 取出列表当前迭代的成员
 *
 * @note 迭代器会在列表Push或Pop时自动重置
 * @param self: 列表对象
 * @return 取出的成员，NULL则取出失败（列表为空，或列表未正确创建）
 */
void* MListIteratorPop(MList *self);

#endif  // _M_LIST_H_
